Initial set of updates to documentation for Stretch by WasabiFan · Pull Request #411 · ev3dev/ev3dev-lang-python

WasabiFan · 2017-10-13T23:42:34Z

This is an initial set of documentation updates for Stretch. I rearranged the README so it made a bit more sense to me, added information about the VSCode extension, and added an "upgrading guide".

I'd like a thorough check from others to make sure I didn't do anything stupid

TODOs:

Update information on required kernel version
Unfinished area at the bottom of the new file (I expect to create an additional page for this; the idea is to have a page explaining the new features)
Documentation for special sensor classes is broken (time to learn how this rST stuff works)
(existing) "Module Index" link at bottom of homepage broken

I'm finding it a bit ugly to have to explain adding additional classes to the import list; read it over and tell me what you guys think.

Fixes #399

WasabiFan · 2017-10-13T23:47:37Z

It looks like there's some messed-up formatting which I need to fix: http://ev3dev-lang.readthedocs.io/projects/python-ev3dev/en/stretch-documentation/

If you aren't a maintainer, don't click this link; it isn't complete documentation.

ddemidov · 2017-10-14T06:29:44Z


-Usage Examples
+Usage
 --------------


The underlines should be same length as the titles.

ddemidov · 2017-10-14T06:37:45Z


-If you are using a BrickPi, use this line:
+To be able to run your Python file, **your program must be executable**. If
+you're using the `ev3dev Visual Studio Code extension`_, this step will be


I think "If you're using the ev3dev Visual Studio Code extension_, you can skip this step, since it will be automatically performed when you download your code to the brick." sounds better. Otherwise it sounds like you can skip this step in any case.

ddemidov · 2017-10-14T06:44:25Z

-This little program will run the motor at 500 ticks per second, which on the EV3
-"large" motors equates to around 1.4 rotations per second, for three seconds
-(3000 milliseconds).
+This will run a LEGO Large Motor at 75% power for 5 rotations.


Is it power or speed?

ddemidov · 2017-10-14T06:44:43Z

-
-
+  m = LargeMotor(OUTPUT_A)
+  m.on_for_rotations(75, 5)


This is offtopic, but looking at this line of code I feel it could be more readable. Is 75 here power or rotations? Why the power attribute is on the first place when the method is called on_for_rotations? Why not m.on_for_rotations(5, power=75)?

We can use the new methodology from #407

WasabiFan · 2018-03-04T03:45:00Z

@dwalton76 why's this closed?

dwalton76 · 2018-03-04T11:59:54Z

@WasabiFan weird it looks like when I deleted develop (since it was a duplicate of stretch) it closed any open PRs against it.

WasabiFan · 2018-06-10T00:53:11Z

Note: we probably need to add a note somewhere in the Jessie docs to point people to Stretch, and maybe vice versa as well, because web search results might pick up both.

WasabiFan · 2018-06-10T02:34:54Z

We should figure out how to make the on_* methods more discoverable. At the moment a docs page for a motor class has them listed 2/3rds down the class section, intermingled with a bunch of properties we hope no one will ever have to use. The easiest way is probably a usage example at the top of the section.

WasabiFan · 2018-06-10T03:49:51Z

 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
+
+autodoc_member_order = 'bysource'


I'd like some feedback on this change. I'm hoping it might make things a bit more logical to sort through... not sure.

Both bysource (more logical order) and alphabetical (easier to find things) make sense to me. Too bad users can not change this dynamically.

WasabiFan · 2018-06-10T23:39:51Z

The current implementations of the Move* classes are a bit weird right now. MoveTank extends from MotorSet and implements the on_for_* and related methods appropriately. MoveSteering then extends from MoveTank and overrides those methods to take the steering parameter rather than individual values. But while it implements on, it doesn't implement off. So in that case we're expecting people to realize that they should look at the super class for that particular method. Then we have the MoveJoystick class which also extends MoveTank; but because running for a particular distance doesn't make much sense for joystick control (it is almost solely for human operation), we don't override the other on_for_* methods with new parameters. That means that a MoveJoystick has an on_for_rotations method, for example, but it's actually pointless because it only takes tank parameters. This isn't great for either documentation purposes or IDE suggestions.

The two solutions I see are:

Explicitly implement an off method on the MoveSteering class (quick fix). This at least removes the primary mixed messagingby eliminating the need to look at the superclass, although there are other methods on the superclasses which you might want to use anyway, e.g. state checking.
Refactor MoveJoystick so it isn't derived from the other classes. This means that you lose the potentially helpful properties and methods on that class from its parents. This might work well if we had a publically-accessible instance of the inner MoveTank which could be operated on directly when needed.

WasabiFan · 2018-06-27T03:15:35Z

@dwalton76 @ddemidov Could I get a review of this? I'd like to see if we can merge this and get a Stretch release out.

Question: where should we put info on usage of the new features? A dedicated page just for this version transition? An announcement (ev3dev.org maybe)? A new changelog? Just with each individual class?

It seemed pretty useless to me given that we have the "tree" immediately above it.

WasabiFan · 2018-07-14T05:36:53Z

Item for discussion: Where do we link to the new upgrading guide?

ddemidov · 2018-07-16T11:04:01Z

Item for discussion: Where do we link to the new upgrading guide?

Would a "danger note" somewhere around Getting Started / Usage work? Something like

This documents the new "stretch" version of the library. If you are using older, "jessie" ev3dev installation, go to the older documentation [here]. If you are upgrading from "jessie", look at the [upgrade guide].

ddemidov

Wow, that is a lot of work! I went though this commit by commit, and it looks good to me. I did not check for completeness (or that the compiled docs actually look good), but I think its better if we merge this and then keep updating the docs as necessary.

WasabiFan · 2018-07-17T01:55:20Z

Thanks for the review! I've merged this and will go update #480 to rebase it on stretch.

ndward · 2018-07-25T22:19:00Z

I'd like to make some more videos for beginners about the VS Code workflow but I don't want to make videos that will quickly be made out of date by the (exciting) introduction of the movetank and movesteering classes. It would be very helpful if you could estimate a date for the initial Stretch release of the Python library.

WasabiFan · 2018-07-25T23:05:41Z

I intend to release within a day after I merge #480 and #483, which contain important port name updates and some usability improvements for the Move* classes. Those are waiting on review (other maintainers have been more busy than I have recently). I just posted in #480 again as a reminder and hopefully we can get things finished and published soon. I do legitimately plan to get this released ASAP.

How about this: If they aren't already merged by mid-day Sunday (my time, PST) I'll merge them anyway 😆 Then I'll test things out to make sure that all of that code works and publish to PyPi. It might take a day or two past that to either figure out how to publish the Debian package myself or get someone else to do it.

ddemidov · 2018-07-26T06:24:14Z

I think I still have VM image I used to publish the debian packages, so I could try to make the release when you say it's ready. Although, it may be better if you tried to do it yourself :)

WasabiFan · 2018-07-26T16:22:10Z

Yeah, I can definitely look into it. I know there's a docs page on it at ev3dev.org (which I might need to adapt for Stretch); the issue is that, once I have built the package, I'll need permissions to actually deploy it anywhere 😆 I'll first just need to get the thing building.

WasabiFan requested review from ddemidov and dwalton76 October 13, 2017 23:42

ddemidov reviewed Oct 14, 2017

View reviewed changes

WasabiFan mentioned this pull request Oct 19, 2017

API Plans? #419

Closed

WasabiFan mentioned this pull request Jan 8, 2018

Bring documentation up-to-date with the develop branch #442

Merged

dwalton76 closed this Mar 4, 2018

WasabiFan mentioned this pull request Jun 10, 2018

Stretch documentation – ev3dev2 module (aka ev3dev-stretch, library v2) #473

Closed

WasabiFan changed the base branch from develop to stretch June 10, 2018 00:47

WasabiFan reopened this Jun 10, 2018

WasabiFan force-pushed the stretch-documentation branch from 5431397 to 6e87447 Compare June 10, 2018 01:01

WasabiFan commented Jun 10, 2018

View reviewed changes

WasabiFan mentioned this pull request Jun 27, 2018

YouTube videos to promote the VS Code workflow ev3dev/vscode-ev3dev-browser#61

Closed

WasabiFan added 8 commits July 13, 2018 19:37

Initial set of updates to documentation for Stretch

290bd5f

Remove "indices and tables" section of home page

2422302

It seemed pretty useless to me given that we have the "tree" immediately above it.

Update navbar link

f15a1a2

Improvements to motor docs

3b1d708

Add a new SpeedInteger for percentage and improve related docs

10fa4e8

More motor docs improvements

59e8899

README updates

d634772

Continue iterating on motor docs and readme

408c802

Update sensor docs page

192df65

WasabiFan force-pushed the stretch-documentation branch from 5e89179 to 192df65 Compare July 14, 2018 02:42

WasabiFan mentioned this pull request Jul 14, 2018

Accept unit classes in motor groups #480

Merged

WasabiFan added 4 commits July 13, 2018 21:45

Add new section to Stretch upgrade guide on new features

8cdd2ff

Attempt to fix docs build

10a098b

Add WIP section

002366f

Clean-up and new drive example

b50cd80

Add docs build validation to Travis

49706b8

WasabiFan force-pushed the stretch-documentation branch from 9e58bea to 49706b8 Compare July 15, 2018 01:32

ddemidov approved these changes Jul 16, 2018

View reviewed changes

Update README.rst

64ddb99

WasabiFan merged commit 6af0b14 into stretch Jul 17, 2018

WasabiFan deleted the stretch-documentation branch July 18, 2018 03:49

Conversation

WasabiFan commented Oct 13, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

WasabiFan commented Oct 13, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ddemidov Oct 14, 2017

Choose a reason for hiding this comment

Uh oh!

ddemidov Oct 14, 2017

Choose a reason for hiding this comment

Uh oh!

ddemidov Oct 14, 2017

Choose a reason for hiding this comment

Uh oh!

ddemidov Oct 14, 2017

Choose a reason for hiding this comment

Uh oh!

ddemidov Oct 14, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

WasabiFan Oct 14, 2017

Choose a reason for hiding this comment

Uh oh!

WasabiFan commented Mar 4, 2018

Uh oh!

dwalton76 commented Mar 4, 2018

Uh oh!

WasabiFan commented Jun 10, 2018

Uh oh!

WasabiFan commented Jun 10, 2018

Uh oh!

WasabiFan Jun 10, 2018

Choose a reason for hiding this comment

Uh oh!

ddemidov Jul 16, 2018

Choose a reason for hiding this comment

Uh oh!

WasabiFan commented Jun 10, 2018

Uh oh!

WasabiFan commented Jun 27, 2018

Uh oh!

WasabiFan commented Jul 14, 2018

Uh oh!

ddemidov commented Jul 16, 2018

Uh oh!

ddemidov left a comment

Choose a reason for hiding this comment

Uh oh!

WasabiFan commented Jul 17, 2018

Uh oh!

ndward commented Jul 25, 2018

Uh oh!

WasabiFan commented Jul 25, 2018

Uh oh!

ddemidov commented Jul 26, 2018

Uh oh!

WasabiFan commented Jul 26, 2018

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

WasabiFan commented Oct 13, 2017 •

edited

Loading

WasabiFan commented Oct 13, 2017 •

edited

Loading

ddemidov Oct 14, 2017 •

edited

Loading